home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / dfield.arc / DFIELD.TXT < prev   
Text File  |  1985-11-22  |  16KB  |  595 lines
  1.  
  2.  
  3.  
  4.  
  5.         DATA FIELD UTILITIES                            LIBRARY FUNCTIONS
  6.  
  7.  
  8.         NAME
  9.  
  10.         init_sread     Initialize data structures for screen package
  11.  
  12.  
  13.         SYNOPSIS
  14.  
  15.         int init_sread()
  16.  
  17.  
  18.         FUNCTION
  19.  
  20.         Initializes  the  data  structures and variables for  the  screen 
  21.         handling routines.  Writes 0 or blank strings to all data storage 
  22.         areas.   Must be called before  get_picture,  get_horizontal,  or 
  23.         sread are used.
  24.  
  25.  
  26.         RETURNS
  27.  
  28.         Nothing.
  29.  
  30.  
  31.         EXAMPLE
  32.  
  33.           {
  34.           char  data[4];
  35.  
  36.           init_sread();      /* Initialize the data structure first */
  37.           strcpy(data,"   ");
  38.           get_picture(0,5,data,"999");
  39.           sread(0);
  40.           }
  41.  
  42.              
  43.         SEE ALSO
  44.  
  45.         get_picture, get_horizontal, sread
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.                                         1
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.         DATA FIELD UTILITIES                            LIBRARY FUNCTIONS
  72.  
  73.  
  74.         NAME
  75.  
  76.         get_picture    set up for latter screen gathering of data
  77.  
  78.  
  79.         SYNOPSIS
  80.  
  81.         int  get_picture(x,y,data,verify)
  82.         unsigned char x,    /* X coordinate for start of field */
  83.                       y;    /* Y coordinate for start of field */
  84.         char  *data,        /* pointer to where data is to be saved */
  85.               *verify;      /* pointer to verification string for data */
  86.  
  87.  
  88.         FUNCTION
  89.  
  90.         Repeated  use of this function allows a "picture" to be built  up 
  91.         of how data fields should be collected from the screen.   Data is 
  92.         gathered  by  fields.   Each  use  of  the  get_picture  function 
  93.         describes  one  data  field.   This description tells  the  SREAD 
  94.         program where on the screen to gather that data,  where to  store 
  95.         the  data,  and  what to verify the data against AS IT  IS  BEING 
  96.         ENTERED.   Data is always gathered as strings of ASCII characters 
  97.         and fields look as follows:
  98.  
  99.         [       ]
  100.  
  101.         Thus to gather a 4 character data field will require 6 characters 
  102.         on the screen,  four for data and two delimiters "[" & "]".  Your 
  103.         data  storage  area  only sees the four data characters  (and  of 
  104.         course the standard C string delimiter 0).
  105.  
  106.         When a data field is described an input string must be specified.  
  107.         This  string  will be used to store ASCII data input  during  the 
  108.         SREAD  function.   This  string MUST be initialized to  the  same 
  109.         length  as  the verification string.   The length  of  the  input 
  110.         string  is  used to determine the width of the data  field.   ANY 
  111.         data  in the data field will be displayed and preserved by  SREAD 
  112.         unless new data is entered over it.   Thus default values can  be 
  113.         initialized in variables and will remain there unless changed.
  114.  
  115.         Cursor  positioning begins in the upper left hand corner  of  the 
  116.         screen.  This position is 0,0 (X,Y).  The horizontal position can 
  117.         range  from 0 to 79,  while the vertical can go from 0 to 24.   A 
  118.         maximum  of 50 data fields may be specified with the  get_picture 
  119.         command before an sread() command must be issued.
  120.  
  121.         Sub-field  separators are possible with this  function.   Special 
  122.         characters used in the verification string such as / - : etc will 
  123.         not  actually be verified.   They indicate a sub-field separation 
  124.         and  do  not need to be typed by the person entering  data  under 
  125.         SREAD.  Thus a date might have a verification string of MM/DD/YY.  
  126.  
  127.  
  128.                                         2
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.         DATA FIELD UTILITIES                            LIBRARY FUNCTIONS
  138.  
  139.  
  140.         The  operator enters only the MM,  DD,  & YY  numbers.   The  "/" 
  141.         character  is  displayed and stored in the data string but  typed 
  142.         automatically  by  the  program not  the  operator.   The  rubout 
  143.         command  recognizes these special characters and deals with  them 
  144.         accordingly.   NOTES: No verification field may start or end with 
  145.         a  sub-field separator.   No two sub-field separators can  appear 
  146.         consecutively.
  147.  
  148.         A   great   deal  of  normal  data  verification  can   be   done 
  149.         automatically  under  the control of  the  SREAD  program.   This 
  150.         verification  must  be  specified in  the  GET_PICTURE  function.  
  151.         There  are  two general types of data verification.   These  are: 
  152.         single character, and double character.  The following two tables 
  153.         list the verification characters and their uses:
  154.  
  155.  
  156.                                 Verify Characters
  157.                  Doubles                           Singles
  158.         =================================================================
  159.              MM  month (1 - 12)            |    9  numeric only
  160.              DD  day (1 - 31)              |    X  alpha-numeric
  161.              YY  year (70 - 99)            |    A  alpha only
  162.              HH  hour (1 - 12)             |    U  convert to upper case
  163.              SS  seconds (0 - 59)          |    L  logical (Y,N,T,F)
  164.              PP  AM or PM (M automatic)    |   " " anything 
  165.                                            |    I  invisible (password)
  166.  
  167.  
  168.         Verification strings are normally fed to the GET_PICTURE function 
  169.         through the use of a permanent data string.   This makes  reading 
  170.         the  program code easier.   The string "MM/DD/YY" forces SREAD to 
  171.         only allow the entry of valid months,  days,  and years as  data.  
  172.         In  a  similar fashion the other verification characters  can  be 
  173.         used  to ensure proper data entry with little need for extra data 
  174.         checks.
  175.  
  176.  
  177.         RETURNS
  178.  
  179.         TRUE  (!0)  if  information  entered  into  structure  for  later 
  180.         collection.  FALSE (0) if structure is full error.
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.                                         3
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.         DATA FIELD UTILITIES                            LIBRARY FUNCTIONS
  204.  
  205.  
  206.         EXAMPLE
  207.  
  208.           {
  209.           char  data5[4],data6[4],data7[4],data8[4];
  210.  
  211.           strcpy(data5,"   ");  /* data fields must be initialized */
  212.           strcpy(data6,"   ");  /* before they are used.  Must be  */
  213.           strcpy(data7,"   ");  /* same length as verify string    */
  214.           strcpy(data8,"   ");
  215.  
  216.           get_picture(10,10,data5,"UUU");  /* define data field 1 */
  217.           get_picture(10,13,data6,"999");  /* this is field 2     */
  218.           get_picture(10,15,data7,"SS");   /* now for field 3     */
  219.           get_picture(10,17,data8,"XXX");  /* last field in num 4 */
  220.           sread(0);                        /* go get all fields   */
  221.           }
  222.  
  223.  
  224.         SEE ALSO
  225.  
  226.         init_sread, get_horizontal, sread
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.                                         4
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.         DATA FIELD UTILITIES                            LIBRARY FUNCTIONS
  270.  
  271.  
  272.         NAME
  273.  
  274.         get_horizontal      set up multiple data field collection
  275.  
  276.  
  277.         SYNOPSIS
  278.  
  279.         int  get_horizontal(x,y,num_entries,spacing,data,verify)
  280.         unsigned char x,    /* X coordinate for start of field */
  281.                       y,    /* Y coordinate for start of field */
  282.                       num_entries,  /* number of entries to get */
  283.                       spacing;  /* space to be left between fields */
  284.         char  *data[],      /* array of pointers to data to be saved */
  285.               *verify;      /* pointer to verification string for data */
  286.  
  287.  
  288.         FUNCTION
  289.  
  290.         This  command  performs  a  function  very  similar  to  that  of 
  291.         GET_PICTURE.   All  explanations of data entry  and  verification 
  292.         under  the  GET_PICTURE  command  apply  here  and  will  not  be 
  293.         repeated.
  294.  
  295.         GET_HORIZONTAL  is  used  when a number of data  fields  must  be 
  296.         entered  on  a single line and their data  saved.   The  function 
  297.         offers  the added feature that when data is entered  under  SREAD 
  298.         and  a field is left blank then all following fields on this line 
  299.         will  be skipped.   Thus a variable number of data fields can  be 
  300.         collected and still use the full editing features of SREAD.
  301.  
  302.         A typical use might be as follows:
  303.  
  304.  
  305.         get_horizontal(10,5,4,2,data,"999");
  306.  
  307.  
  308.         Which would display four fields in the form:
  309.  
  310.  
  311.                   [   ]  [   ]  [   ]  [   ]
  312.  
  313.  
  314.         If two data fields are entered,  the operator only needs to hit a 
  315.         return  on  the  third field to skip to the next  line  of  data: 
  316.         bypassing the fourth and any successive fields.
  317.  
  318.         The  GET_PICTURE and GET_HORIZONTAL commands may be intermixed in 
  319.         any  manner you please.   The only limitations are on  the  total 
  320.         number of data fields allowed,  typically 50 fields.
  321.  
  322.  
  323.  
  324.  
  325.  
  326.                                         5
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.         DATA FIELD UTILITIES                            LIBRARY FUNCTIONS
  336.  
  337.  
  338.         RETURNS
  339.  
  340.         TRUE  (!0)  if  information  entered  into  structure  for  later 
  341.         collection.  FALSE (0) if structure is full error.
  342.  
  343.  
  344.         EXAMPLE
  345.  
  346.           {
  347.           char  *pointer[];
  348.           char  dat1[4],dat2[4],dat3[4],dat4[4];
  349.  
  350.           strcpy(dat1,"   ");  /* initialize data strings first */
  351.           strcpy(dat2,"   ");
  352.           strcpy(dat3,"   ");
  353.           strcpy(dat4,"   ");
  354.  
  355.           pointer[0] = dat1;  /* initialize array of pointers */
  356.           pointer[1] = dat2;
  357.           pointer[2] = dat3;
  358.           pointer[3] = dat4;
  359.  
  360.           init_sread();
  361.           get_horizontal(0,20,4,5,pointer,"999");
  362.           sread(0);
  363.  
  364.           }
  365.  
  366.         This  example  will  input up to four numeric  strings  of  three 
  367.         digits each.  All are verified against the same string "999".
  368.  
  369.         SEE ALSO
  370.  
  371.         init_sread, get_picture, sread
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.                                         6
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.         DATA FIELD UTILITIES                            LIBRARY FUNCTIONS
  402.  
  403.  
  404.         NAME
  405.  
  406.         sread     (screen read)  Go get all PREVIOUSLY requested data
  407.  
  408.  
  409.         SYNOPSIS
  410.  
  411.         int  sread(where)
  412.         int  where       /* What field to start reading data from */
  413.  
  414.          
  415.         FUNCTION
  416.  
  417.         Collect  all  data  fields previously  specified  by  either  the 
  418.         get_picture or get_horizontal commands.  This includes all fields 
  419.         specified  by  get_picture or get_horizontal commands  since  the 
  420.         last issue of an init_sread command.
  421.  
  422.         Input   variable  WHERE  controls  where,   (what  field),   data 
  423.         collection  will start and whether the exit data collection  key, 
  424.         ctrl-W,  functions.  (You can thus force all data to be entered.)  
  425.         No check is made on WHERE to see if it is larger that the  number 
  426.         of fields requested.
  427.  
  428.  
  429.         WHERE     May range from 0 to N, where N is the maximum number of 
  430.                   data fields requested.
  431.  
  432.         WHERE = 0      Specifies  start at data field 1,  disable  ctrl-W 
  433.                        (exit all data collection)
  434.  
  435.         WHERE = 1 - N  Start data collection at specified data field  and 
  436.                        enable the ctrl-W function.
  437.  
  438.  
  439.         While  the  SREAD  command is functioning the  following  control 
  440.         characters will operate as follows:
  441.  
  442.  
  443.         ctrl-A    Move  the cursor one field backward.   Not possible  is 
  444.                   data  has  already been entered in this field or if  at 
  445.                   first field.  Beep error message then.
  446.  
  447.         ctrl-F    Move  the cursor one field forward,  and on last  field 
  448.                   exit.   Not  possible if data already entered  in  this 
  449.                   field,  (beep error message).  Acts exactly the same as 
  450.                   a carriage return.
  451.  
  452.         ctrl-W    If  this  function  is enabled,  (by passing 1  - n  to 
  453.                   SREAD)  and no data has yet been entered in this  field 
  454.                   will cause SREAD to terminate operations with  whatever 
  455.                   data has already been collected.
  456.  
  457.  
  458.                                         7
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.         DATA FIELD UTILITIES                            LIBRARY FUNCTIONS
  468.  
  469.  
  470.  
  471.         CR        Carriage return- Enter all data in this field,  move to 
  472.                   next field.   Data must pass verification.   If no data 
  473.                   entered  CR  will  reenter old data and  move  to  next 
  474.                   field.
  475.  
  476.         RUB       Delete  last character entered unless at  beginning  of 
  477.                   field.   Beeps  on error.   Will automatically back  up 
  478.                   across "neutral" data, ( / - , . ).
  479.  
  480.  
  481.         RETURNS
  482.  
  483.         TRUE  (!0)  if  premature  exit  through  the  use  of  control-W 
  484.         function,  FALSE  (0) otherwise.   NOTE:  If sread is called  and 
  485.         passed a 0 this disables the ctrl-W function, thus only FALSE may 
  486.         be returned in this case.
  487.  
  488.  
  489.         EXAMPLE
  490.  
  491.           {
  492.  
  493.           get_picture(5,5,data,"L");
  494.           get_picture(5,6,data2,"AA");
  495.           sread(0);    /* Start reading in field 1, NO ctrl-W allowed */
  496.  
  497.           get_picture(0,1,data3,"999");
  498.           get_picture(0,3,data4,"999");
  499.           sread(1);    /* Start reading in field 1, ctrl-W allowed */
  500.  
  501.           get_picture(10,10,data5,"999");
  502.           get_picture(10,13,data6,"999");
  503.           get_picture(10,15,data7,"999");
  504.           get_picture(10,17,data8,"999");
  505.           sread(2);    /* Start reading in field 2, ctrl-W allowed    */
  506.                        /* Field 1 has been skipped, may be reached by */
  507.                        /* ctrl-A key (back up a field)                */
  508.  
  509.  
  510.         SEE ALSO
  511.  
  512.         init_sread, get_picture, get_horizontal
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.                                         8
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.         DATA FIELD UTILITIES                            LIBRARY FUNCTIONS
  534.  
  535.  
  536.                                 Lattice Utilities
  537.  
  538.         These object file utilities are being distributed at no charge to 
  539.         all people who are interested in obtaining them.  The BBS form of 
  540.         these files includes only the large code - large data model (-ml) 
  541.         object  files  and matching documentation.   If  these  utilities 
  542.         sound  interesting try them out.   We will supply the source code 
  543.         on an IBM PC DSDD disk to these utilities,  so you can use any of 
  544.         the four memory models, for a price of $25.00.
  545.  
  546.         Users  of this software may incorporate it into any product  they 
  547.         desire.   There  is no charge for this.   You may NOT  sell  this 
  548.         package by itself in any form what so ever.   The only exceptions 
  549.         to  this  are a limited distribution fee for Clubs and  or  Users 
  550.         Groups not to exceed $10.00 per disk.
  551.  
  552.  
  553.                                     Warranty
  554.  
  555.         NONE!   We  are not responsible or liable for any damages  either 
  556.         real  or consequential.   This package is free after  all.   Note 
  557.         that   this  software  has  been  running  in  several  different 
  558.         commercial  packages for three years now so it must do  something 
  559.         right.
  560.  
  561.  
  562.              Copyright 1983, 1984, 1985 by Elfring Consulting, Inc.
  563.  
  564.                                All rights reserved
  565.  
  566.  
  567.  
  568.         Full source code is available for $25.00 from:
  569.  
  570.              Elfring Consulting, Inc.
  571.              4N899 W. Mary Drive
  572.              St. Charles, Illinois
  573.              60174
  574.  
  575.              312-377-3520
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.                                         9
  591.  
  592.  
  593.  
  594.  
  595.